home *** CD-ROM | disk | FTP | other *** search
/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / MacOS 8 Resources / Developer Tools / Mac OS 8 Interfaces & Libraries / Interfaces / CIncludes / OSA.h < prev    next >
C/C++ Source or Header  |  1996-05-01  |  56KB  |  1,719 lines
  1. /*
  2.      File:        OSA.h
  3.  
  4.      Contains:    AppleScript Client Interfaces.
  5.  
  6.      Version:    Technology:    AppleScript 1.1
  7.                  Release:    Universal Interfaces 3.0d3 on Copland DR1
  8.  
  9.      Copyright:    © 1984-1996 by Apple Computer, Inc.  All rights reserved.
  10.  
  11.      Bugs?:        If you find a problem with this file, send the file and version
  12.                  information (from above) and the problem description to:
  13.  
  14.                      Internet:    apple.bugs@applelink.apple.com
  15.                      AppleLink:    APPLE.BUGS
  16.  
  17. */
  18. #ifndef __OSA__
  19. #define __OSA__
  20.  
  21. #ifndef __ERRORS__
  22. #include <Errors.h>
  23. #endif
  24. #ifndef __APPLEEVENTS__
  25. #include <AppleEvents.h>
  26. #endif
  27. #ifndef __AEOBJECTS__
  28. #include <AEObjects.h>
  29. #endif
  30. #ifndef __COMPONENTS__
  31. #include <Components.h>
  32. #endif
  33.  
  34. #ifdef __cplusplus
  35. extern "C" {
  36. #endif
  37.  
  38. #if PRAGMA_IMPORT_SUPPORTED
  39. #pragma import on
  40. #endif
  41.  
  42. #if PRAGMA_ALIGN_SUPPORTED
  43. #pragma options align=mac68k
  44. #endif
  45.  
  46. #if FOR_SYSTEM7_ONLY
  47. /*
  48. *************************************************************************
  49.     Types and Constants
  50. *************************************************************************
  51. */
  52. /*
  53.     The componenent manager type code for components that
  54.         support the OSA interface defined here. 
  55. */
  56. /* 0x6f736120 */
  57.  
  58. enum {
  59.     kOSAComponentType            = 'osa '
  60. };
  61.  
  62. /* 0x73637074 */
  63.  
  64. enum {
  65.     kOSAGenericScriptingComponentSubtype = 'scpt'
  66. };
  67.  
  68. /*    Type of script document files.    */
  69. /* 0x6f736173 */
  70.  
  71. enum {
  72.     kOSAFileType                = 'osas'
  73. };
  74.  
  75. /*
  76.         Suite and event code of the RecordedText event. 
  77.         (See OSAStartRecording, below.)
  78. */
  79. /* 0x61736372 */
  80.  
  81. enum {
  82.     kOSASuite                    = 'ascr'
  83. };
  84.  
  85. /* 0x72656364 */
  86.  
  87. enum {
  88.     kOSARecordedText            = 'recd'
  89. };
  90.  
  91. /* Selector returns boolean */
  92. /* 0x6d6f6469 */
  93.  
  94. enum {
  95.     kOSAScriptIsModified        = 'modi'
  96. };
  97.  
  98. /* Selector returns boolean */
  99. /* 0x63736372 */
  100.  
  101. enum {
  102.     kOSAScriptIsTypeCompiledScript = 'cscr'
  103. };
  104.  
  105. /* Selector returns boolean */
  106. /* 0x76616c75 */
  107.  
  108. enum {
  109.     kOSAScriptIsTypeScriptValue    = 'valu'
  110. };
  111.  
  112. /* Selector returns boolean */
  113. /* 0x636e7478 */
  114.  
  115. enum {
  116.     kOSAScriptIsTypeScriptContext = 'cntx'
  117. };
  118.  
  119. /* Selector returns a DescType which may be passed to OSACoerceToDesc */
  120. /* 0x62657374 */
  121.  
  122. enum {
  123.     kOSAScriptBestType            = 'best'
  124. };
  125.  
  126. /*
  127.         This selector is used to determine whether a script has source 
  128.         associated with it that when given to OSAGetSource, the call will not
  129.         fail.  The selector returns a boolean.
  130. */
  131. /* 0x67737263 */
  132.  
  133. enum {
  134.     kOSACanGetSource            = 'gsrc'
  135. };
  136.  
  137.  
  138. enum {
  139.     typeOSADialectInfo            = 'difo',                        /*  0x6469666f   */
  140.     keyOSADialectName            = 'dnam',                        /*  0x646e616d   */
  141.     keyOSADialectCode            = 'dcod',                        /*  0x64636f64   */
  142.     keyOSADialectLangCode        = 'dlcd',                        /*  0x646c6364   */
  143.     keyOSADialectScriptCode        = 'dscd'                        /*  0x64736364   */
  144. };
  145.  
  146. typedef ComponentResult OSAError;
  147. /* Under the Open Scripting Architecture all error results are longs */
  148. typedef unsigned long OSAID;
  149. /*
  150.         OSAIDs allow transparent manipulation of scripts associated with
  151.          various scripting systems.
  152. */
  153.  
  154. enum {
  155.     kOSANullScript                = 0L
  156. };
  157.  
  158. /* No -script constant. */
  159.  
  160. enum {
  161.     kOSANullMode                = 0,                            /* sounds better */
  162.     kOSAModeNull                = 0                                /* tastes consistent */
  163. };
  164.  
  165. /*
  166.         Some routines take flags that control their execution.  This constant
  167.         declares default mode settings are used.
  168. */
  169. typedef pascal OSErr (*OSACreateAppleEventProcPtr)(AEEventClass theAEEventClass, AEEventID theAEEventID, const AEAddressDesc *target, short returnID, long transactionID, AppleEvent *result, long refCon);
  170. typedef pascal OSErr (*OSASendProcPtr)(const AppleEvent *theAppleEvent, AppleEvent *reply, AESendMode sendMode, AESendPriority sendPriority, long timeOutInTicks, AEIdleUPP idleProc, AEFilterUPP filterProc, long refCon);
  171.  
  172. #if GENERATINGCFM
  173. typedef UniversalProcPtr OSACreateAppleEventUPP;
  174. typedef UniversalProcPtr OSASendUPP;
  175. #else
  176. typedef OSACreateAppleEventProcPtr OSACreateAppleEventUPP;
  177. typedef OSASendProcPtr OSASendUPP;
  178. #endif
  179.  
  180. enum {
  181.     uppOSACreateAppleEventProcInfo = kPascalStackBased
  182.          | RESULT_SIZE(SIZE_CODE(sizeof(OSErr)))
  183.          | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(AEEventClass)))
  184.          | STACK_ROUTINE_PARAMETER(2, SIZE_CODE(sizeof(AEEventID)))
  185.          | STACK_ROUTINE_PARAMETER(3, SIZE_CODE(sizeof(const AEAddressDesc *)))
  186.          | STACK_ROUTINE_PARAMETER(4, SIZE_CODE(sizeof(short)))
  187.          | STACK_ROUTINE_PARAMETER(5, SIZE_CODE(sizeof(long)))
  188.          | STACK_ROUTINE_PARAMETER(6, SIZE_CODE(sizeof(AppleEvent *)))
  189.          | STACK_ROUTINE_PARAMETER(7, SIZE_CODE(sizeof(long))),
  190.     uppOSASendProcInfo = kPascalStackBased
  191.          | RESULT_SIZE(SIZE_CODE(sizeof(OSErr)))
  192.          | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(const AppleEvent *)))
  193.          | STACK_ROUTINE_PARAMETER(2, SIZE_CODE(sizeof(AppleEvent *)))
  194.          | STACK_ROUTINE_PARAMETER(3, SIZE_CODE(sizeof(AESendMode)))
  195.          | STACK_ROUTINE_PARAMETER(4, SIZE_CODE(sizeof(AESendPriority)))
  196.          | STACK_ROUTINE_PARAMETER(5, SIZE_CODE(sizeof(long)))
  197.          | STACK_ROUTINE_PARAMETER(6, SIZE_CODE(sizeof(AEIdleUPP)))
  198.          | STACK_ROUTINE_PARAMETER(7, SIZE_CODE(sizeof(AEFilterUPP)))
  199.          | STACK_ROUTINE_PARAMETER(8, SIZE_CODE(sizeof(long)))
  200. };
  201.  
  202. #if GENERATINGCFM
  203. #define NewOSACreateAppleEventProc(userRoutine)        \
  204.         (OSACreateAppleEventUPP) NewRoutineDescriptor((ProcPtr)(userRoutine), uppOSACreateAppleEventProcInfo, GetCurrentArchitecture())
  205. #define NewOSASendProc(userRoutine)        \
  206.         (OSASendUPP) NewRoutineDescriptor((ProcPtr)(userRoutine), uppOSASendProcInfo, GetCurrentArchitecture())
  207. #else
  208. #define NewOSACreateAppleEventProc(userRoutine)        \
  209.         ((OSACreateAppleEventUPP) (userRoutine))
  210. #define NewOSASendProc(userRoutine)        \
  211.         ((OSASendUPP) (userRoutine))
  212. #endif
  213.  
  214. #if GENERATINGCFM
  215. #define CallOSACreateAppleEventProc(userRoutine, theAEEventClass, theAEEventID, target, returnID, transactionID, result, refCon)        \
  216.         CallUniversalProc((UniversalProcPtr)(userRoutine), uppOSACreateAppleEventProcInfo, (theAEEventClass), (theAEEventID), (target), (returnID), (transactionID), (result), (refCon))
  217. #define CallOSASendProc(userRoutine, theAppleEvent, reply, sendMode, sendPriority, timeOutInTicks, idleProc, filterProc, refCon)        \
  218.         CallUniversalProc((UniversalProcPtr)(userRoutine), uppOSASendProcInfo, (theAppleEvent), (reply), (sendMode), (sendPriority), (timeOutInTicks), (idleProc), (filterProc), (refCon))
  219. #else
  220. #define CallOSACreateAppleEventProc(userRoutine, theAEEventClass, theAEEventID, target, returnID, transactionID, result, refCon)        \
  221.         (*(userRoutine))((theAEEventClass), (theAEEventID), (target), (returnID), (transactionID), (result), (refCon))
  222. #define CallOSASendProc(userRoutine, theAppleEvent, reply, sendMode, sendPriority, timeOutInTicks, idleProc, filterProc, refCon)        \
  223.         (*(userRoutine))((theAppleEvent), (reply), (sendMode), (sendPriority), (timeOutInTicks), (idleProc), (filterProc), (refCon))
  224. #endif
  225. /*
  226. *************************************************************************
  227.     Standard Script Errors
  228. **************************************************************************
  229.     It is recommended that scripting components use the following set of error
  230.     codes to signal failure when applicable.  This enables applications that
  231.     use the OSA API to deal with some class of script errors in a less than 
  232.     ad hoc manner.  Scripting components are of course encouraged to return
  233.     component-specific errors when these don't apply.
  234. *************************************************************************
  235. */
  236. /*
  237.         Dynamic errors:
  238.  
  239.     These errors result from data-dependent conditions and are typically
  240.     signaled at runtime.
  241. */
  242. /*
  243.         Signaled when a value can't be coerced to the desired type. Similar
  244.           to errOSATypeError except results from coercion.
  245. */
  246.  
  247. enum {
  248.     errOSACantCoerce            = errAECoercionFail
  249. };
  250.  
  251. /* Signaled when an object is not found in a container */
  252.  
  253. enum {
  254.     errOSACantAccess            = errAENoSuchObject
  255. };
  256.  
  257. /*
  258.         Signaled when an object cannot be set in a container.  Same as 
  259.           AERegistry error errAEWriteDenied.
  260. */
  261.  
  262. enum {
  263.     errOSACantAssign            = -10006
  264. };
  265.  
  266. /*
  267.         Signaled by user scripts or applications when no actual error code
  268.           is to be returned.  Simply means "an error has occurred".  Most useful
  269.           in conjunction with an error message from the application.
  270. */
  271.  
  272. enum {
  273.     errOSAGeneralError            = -2700
  274. };
  275.  
  276. /* Signaled when there is an attempt to divide by zero */
  277.  
  278. enum {
  279.     errOSADivideByZero            = -2701
  280. };
  281.  
  282. /* Signaled when integer or real value is too large to be represented */
  283.  
  284. enum {
  285.     errOSANumericOverflow        = -2702
  286. };
  287.  
  288. /*
  289.         Signaled when application can't be launched or when it is remote and
  290.           program linking is not enabled.
  291. */
  292.  
  293. enum {
  294.     errOSACantLaunch            = -2703
  295. };
  296.  
  297. /* Signaled when an application can't respond to AppleEvents */
  298.  
  299. enum {
  300.     errOSAAppNotHighLevelEventAware = -2704
  301. };
  302.  
  303. /* Signaled when an application's terminology resource is not readable */
  304.  
  305. enum {
  306.     errOSACorruptTerminology    = -2705
  307. };
  308.  
  309. /* Signaled when the runtime stack overflows */
  310.  
  311. enum {
  312.     errOSAStackOverflow            = -2706
  313. };
  314.  
  315. /* Signaled when a runtime internal data structure overflows */
  316.  
  317. enum {
  318.     errOSAInternalTableOverflow    = -2707
  319. };
  320.  
  321. /*
  322.         Signaled when an intrinsic limitation is exceeded for the size of 
  323.           a value or data structure.
  324. */
  325.  
  326. enum {
  327.     errOSADataBlockTooLarge        = -2708
  328. };
  329.  
  330.  
  331. enum {
  332.     errOSACantGetTerminology    = -2709
  333. };
  334.  
  335.  
  336. enum {
  337.     errOSACantCreate            = -2710
  338. };
  339.  
  340. /*
  341.         Component-specific dynamic script errors:
  342.  
  343.     The range -2720 thru -2739 is reserved for component-specific runtime errors.
  344.     (Note that error codes from different scripting components in this range will
  345.     overlap.)
  346. */
  347. /*
  348.         Static errors:
  349.  
  350.     These errors comprise what are commonly thought of as parse and compile-
  351.     time errors.  However, in a dynamic system (e.g. AppleScript) any or all
  352.     of these may also occur at runtime.
  353. */
  354. /* Signaled when data was not the right type and coercion is not allowed */
  355.  
  356. enum {
  357.     errOSATypeError                = errAEWrongDataType
  358. };
  359.  
  360. /* Signaled when a message was sent to an object that didn't handle it */
  361.  
  362. enum {
  363.     OSAMessageNotUnderstood        = errAEEventNotHandled
  364. };
  365.  
  366. /*
  367.         Signaled when a function to be returned doesn't exist.  (Probably only
  368.           useful in languages with first-class functions that distinguish between
  369.           functions and other values (two name spaces). This is different from
  370.           errOSAMessageNotUnderstood, which may be signaled when the method is
  371.           invoked.
  372. */
  373.  
  374. enum {
  375.     OSAUndefinedHandler            = errAEHandlerNotFound
  376. };
  377.  
  378. /* Signaled when a container can never have the requested object */
  379.  
  380. enum {
  381.     OSAIllegalAccess            = errAEAccessorNotFound
  382. };
  383.  
  384. /* Signaled when index was out of range. Specialization of errOSACantAccess. */
  385.  
  386. enum {
  387.     OSAIllegalIndex                = errAEIllegalIndex
  388. };
  389.  
  390. /* Signaled when a range is screwy. Specialization of errOSACantAccess. */
  391.  
  392. enum {
  393.     OSAIllegalRange                = errAEImpossibleRange
  394. };
  395.  
  396. /*
  397.         Signaled when an object can never be set in a container.  Same as 
  398.           AERegistry error errAENotModifiable.
  399. */
  400.  
  401. enum {
  402.     OSAIllegalAssign            = -10003
  403. };
  404.  
  405. /*
  406.         Signaled when a syntax error occurs. (e.g. "Syntax error" or
  407.          "<this> can't go after <that>").
  408. */
  409.  
  410. enum {
  411.     OSASyntaxError                = -2740
  412. };
  413.  
  414. /*
  415.         Signaled when another form of syntax was expected. (e.g. "expected
  416.           a <type> but found <this>").
  417. */
  418.  
  419. enum {
  420.     OSASyntaxTypeError            = -2741
  421. };
  422.  
  423. /* Signaled when a name or number is too long to be parsed */
  424.  
  425. enum {
  426.     OSATokenTooLong                = -2742
  427. };
  428.  
  429. /*
  430.         Signaled when a parameter is missing for a function invocation.  Note
  431.           that in some languages, this error may occur at runtime.
  432. */
  433.  
  434. enum {
  435.     OSAMissingParameter            = errAEDescNotFound
  436. };
  437.  
  438. /*
  439.         Signaled when function is called with the wrong number of parameters,
  440.           or a parameter pattern cannot be matched.
  441. */
  442.  
  443. enum {
  444.     OSAParameterMismatch        = errAEWrongNumberArgs
  445. };
  446.  
  447. /*
  448.         Signaled when a formal parameter, local variable, or instance variable
  449.           is specified more than once.
  450. */
  451.  
  452. enum {
  453.     OSADuplicateParameter        = -2750
  454. };
  455.  
  456. /*
  457.         Signaled when a formal parameter, local variable, or instance variable
  458.           is specified more than once.
  459. */
  460.  
  461. enum {
  462.     OSADuplicateProperty        = -2751
  463. };
  464.  
  465. /*
  466.         Signaled when more than one handler is defined with the same name in 
  467.           a scope where the language doesn't allow it.
  468. */
  469.  
  470. enum {
  471.     OSADuplicateHandler            = -2752
  472. };
  473.  
  474. /* Signaled when a variable is accessed that has no value */
  475.  
  476. enum {
  477.     OSAUndefinedVariable        = -2753
  478. };
  479.  
  480. /*
  481.         Signaled when a variable is declared inconsistently in the same scope,
  482.           such as both local and global.
  483. */
  484.  
  485. enum {
  486.     OSAInconsistentDeclarations    = -2754
  487. };
  488.  
  489. /*
  490.         Signaled when illegal control flow occurs in an application (no catcher
  491.           for throw, non-lexical loop exit, etc.).
  492. */
  493.  
  494. enum {
  495.     OSAControlFlowError            = -2755
  496. };
  497.  
  498. /*
  499.         Component-specific static script errors:
  500.  
  501.     The range -2760 thru -2779 is reserved for component-specific parsing and
  502.     compile-time errors. (Note that error codes from different scripting
  503.     components in this range will overlap.)
  504. */
  505. /*
  506.         Dialect-specific script errors:
  507.  
  508.     The range -2780 thru -2799 is reserved for dialect specific error codes for
  509.     scripting components that support dialects. (Note that error codes from
  510.     different scripting components in this range will overlap, as well as error
  511.     codes from different dialects in the same scripting component.)
  512. */
  513. /*
  514. *************************************************************************
  515.     OSA Interface Descriptions
  516. **************************************************************************
  517.     The OSA Interface is broken down into a required interface, and several
  518.     optional interfaces to support additional functionality.  A given scripting
  519.     component may choose to support only some of the optional interfaces in
  520.     addition to the basic interface.  The OSA Component Flags may be used to 
  521.     query the Component Manager to find a scripting component with a particular
  522.     capability, or determine if a particular scripting component supports a 
  523.     particular capability.
  524. *************************************************************************
  525. */
  526. /* OSA Component Flags: */
  527.  
  528. enum {
  529.     kOSASupportsCompiling        = 0x0002,
  530.     kOSASupportsGetSource        = 0x0004,
  531.     kOSASupportsAECoercion        = 0x0008,
  532.     kOSASupportsAESending        = 0x0010,
  533.     kOSASupportsRecording        = 0x0020,
  534.     kOSASupportsConvenience        = 0x0040,
  535.     kOSASupportsDialects        = 0x0080,
  536.     kOSASupportsEventHandling    = 0x0100
  537. };
  538.  
  539. /* Component Selectors: */
  540.  
  541. enum {
  542.     kOSASelectLoad                = 0x0001,
  543.     kOSASelectStore                = 0x0002,
  544.     kOSASelectExecute            = 0x0003,
  545.     kOSASelectDisplay            = 0x0004,
  546.     kOSASelectScriptError        = 0x0005,
  547.     kOSASelectDispose            = 0x0006,
  548.     kOSASelectSetScriptInfo        = 0x0007,
  549.     kOSASelectGetScriptInfo        = 0x0008,
  550.     kOSASelectSetActiveProc        = 0x0009,
  551.     kOSASelectGetActiveProc        = 0x000A
  552. };
  553.  
  554. /* Compiling: */
  555.  
  556. enum {
  557.     kOSASelectScriptingComponentName = 0x0102,
  558.     kOSASelectCompile            = 0x0103,
  559.     kOSASelectCopyID            = 0x0104
  560. };
  561.  
  562. /* GetSource: */
  563.  
  564. enum {
  565.     kOSASelectGetSource            = 0x0201
  566. };
  567.  
  568. /* AECoercion: */
  569.  
  570. enum {
  571.     kOSASelectCoerceFromDesc    = 0x0301,
  572.     kOSASelectCoerceToDesc        = 0x0302
  573. };
  574.  
  575. /* AESending: */
  576.  
  577. enum {
  578.     kOSASelectSetSendProc        = 0x0401,
  579.     kOSASelectGetSendProc        = 0x0402,
  580.     kOSASelectSetCreateProc        = 0x0403,
  581.     kOSASelectGetCreateProc        = 0x0404,
  582.     kOSASelectSetDefaultTarget    = 0x0405
  583. };
  584.  
  585. /* Recording: */
  586.  
  587. enum {
  588.     kOSASelectStartRecording    = 0x0501,
  589.     kOSASelectStopRecording        = 0x0502
  590. };
  591.  
  592. /* Convenience: */
  593.  
  594. enum {
  595.     kOSASelectLoadExecute        = 0x0601,
  596.     kOSASelectCompileExecute    = 0x0602,
  597.     kOSASelectDoScript            = 0x0603
  598. };
  599.  
  600. /* Dialects: */
  601.  
  602. enum {
  603.     kOSASelectSetCurrentDialect    = 0x0701,
  604.     kOSASelectGetCurrentDialect    = 0x0702,
  605.     kOSASelectAvailableDialects    = 0x0703,
  606.     kOSASelectGetDialectInfo    = 0x0704,
  607.     kOSASelectAvailableDialectCodeList = 0x0705
  608. };
  609.  
  610. /* Event Handling: */
  611.  
  612. enum {
  613.     kOSASelectSetResumeDispatchProc = 0x0801,
  614.     kOSASelectGetResumeDispatchProc = 0x0802,
  615.     kOSASelectExecuteEvent        = 0x0803,
  616.     kOSASelectDoEvent            = 0x0804,
  617.     kOSASelectMakeContext        = 0x0805
  618. };
  619.  
  620. /* scripting component specific selectors are added beginning with this value  */
  621.  
  622. enum {
  623.     kOSASelectComponentSpecificStart = 0x1001
  624. };
  625.  
  626. /*
  627.         Mode Flags:
  628.  
  629.     Warning: These should not conflict with the AESend mode flags in
  630.     AppleEvents.h, because we may want to use them as OSA mode flags too.
  631. */
  632. /*
  633.         This mode flag may be passed to OSALoad, OSAStore or OSACompile to
  634.           instruct the scripting component to not retain the "source" of an
  635.           expression.  This will cause the OSAGetSource call to return the error
  636.           errOSASourceNotAvailable if used.  However, some scripting components
  637.           may not retain the source anyway.  This is mainly used when either space
  638.           efficiency is desired, or a script is to be "locked" so that its
  639.           implementation may not be viewed.
  640. */
  641.  
  642. enum {
  643.     kOSAModePreventGetSource    = 0x00000001
  644. };
  645.  
  646. /*
  647.         These mode flags may be passed to OSACompile, OSAExecute, OSALoadExecute
  648.           OSACompileExecute, OSADoScript, OSAExecuteEvent, or OSADoEvent to
  649.           indicate whether or not the script may interact with the user, switch
  650.           layer or reconnect if necessary.  Any AppleEvents will be sent with the
  651.           corresponding AESend mode supplied.
  652. */
  653.  
  654. enum {
  655.     kOSAModeNeverInteract        = kAENeverInteract,
  656.     kOSAModeCanInteract            = kAECanInteract,
  657.     kOSAModeAlwaysInteract        = kAEAlwaysInteract,
  658.     kOSAModeDontReconnect        = kAEDontReconnect
  659. };
  660.  
  661. /*
  662.         This mode flag may be passed to OSACompile, OSAExecute, OSALoadExecute
  663.           OSACompileExecute, OSADoScript, OSAExecuteEvent, or OSADoEvent to
  664.           indicate whether or not AppleEvents should be sent with the
  665.           kAECanSwitchLayer mode flag sent or not. NOTE: This flag is exactly the
  666.           opposite sense of the AppleEvent flag kAECanSwitchLayer.  This is to
  667.           provide a more convenient default, i.e. not supplying any mode
  668.           (kOSAModeNull) means to send events with kAECanSwitchLayer.  Supplying
  669.           the kOSAModeCantSwitchLayer mode flag will cause AESend to be called
  670.           without kAECanSwitchLayer.
  671. */
  672.  
  673. enum {
  674.     kOSAModeCantSwitchLayer        = 0x00000040
  675. };
  676.  
  677. /*
  678.         This mode flag may be passed to OSACompile, OSAExecute, OSALoadExecute
  679.           OSACompileExecute, OSADoScript, OSAExecuteEvent, or OSADoEvent to
  680.           indicate whether or not AppleEvents should be sent with the kAEDontRecord
  681.           mode flag sent or not. NOTE: This flag is exactly the opposite sense of
  682.           the AppleEvent flag kAEDontRecord.  This is to provide a more convenient
  683.           default, i.e. not supplying any mode (kOSAModeNull) means to send events
  684.           with kAEDontRecord.  Supplying the kOSAModeDoRecord mode flag will 
  685.           cause AESend to be called without kAEDontRecord.
  686. */
  687.  
  688. enum {
  689.     kOSAModeDoRecord            = 0x00001000
  690. };
  691.  
  692. /*
  693.         This is a mode flag for OSACompile that indicates that a context should
  694.           be created as the result of compilation. All handler definitions are
  695.           inserted into the new context, and variables are initialized by
  696.           evaluating their initial values in a null context (i.e. they must be
  697.           constant expressions).
  698. */
  699.  
  700. enum {
  701.     kOSAModeCompileIntoContext    = 0x00000002
  702. };
  703.  
  704. /*
  705.         This is a mode flag for OSACompile that indicates that the previous
  706.           script ID (input to OSACompile) should be augmented with any new
  707.           definitions in the sourceData rather than replaced with a new script.
  708.           This means that the previous script ID must designate a context.
  709.           The presence of this flag causes the kOSAModeCompileIntoContext flag
  710.           to be implicitly used, causing any new definitions to be initialized
  711.           in a null context.
  712. */
  713.  
  714. enum {
  715.     kOSAModeAugmentContext        = 0x00000004
  716. };
  717.  
  718. /*
  719.         This mode flag may be passed to OSADisplay or OSADoScript to indicate
  720.           that output only need be human-readable, not re-compilable by OSACompile.
  721.           If used, output may be arbitrarily "beautified", e.g. quotes may be left
  722.           off of string values, long lists may have elipses, etc.
  723. */
  724.  
  725. enum {
  726.     kOSAModeDisplayForHumans    = 0x00000008
  727. };
  728.  
  729. /*
  730.         This mode flag may be passed to OSAStore in the case where the scriptID
  731.           is a context.  This causes the context to be saved, but not the context's
  732.           parent context.  When the stored context is loaded back in, the parent
  733.           will be kOSANullScript.
  734. */
  735.  
  736. enum {
  737.     kOSAModeDontStoreParent        = 0x00010000
  738. };
  739.  
  740. /*
  741.         This mode flag may be passed to OSAExecuteEvent to cause the event to
  742.           be dispatched to the direct object of the event. The direct object (or
  743.           subject attribute if the direct object is a non-object specifier) will
  744.           be resolved, and the resulting script object will be the recipient of
  745.           the message. The context argument to OSAExecuteEvent will serve as the
  746.           root of the lookup/resolution process.
  747. */
  748.  
  749. enum {
  750.     kOSAModeDispatchToDirectObject = 0x00020000
  751. };
  752.  
  753. /*
  754.         This mode flag may be passed to OSAExecuteEvent to indicate that
  755.           components do not have to get the data of object specifier arguments.
  756. */
  757.  
  758. enum {
  759.     kOSAModeDontGetDataForArguments = 0x00040000
  760. };
  761.  
  762. /*
  763. *************************************************************************
  764.     OSA Basic Scripting Interface
  765. **************************************************************************
  766.     Scripting components must at least support the Basic Scripting interface.
  767. *************************************************************************
  768. */
  769. /*
  770.         Loading and Storing Scripts:
  771.  
  772.     These routines allow scripts to be loaded and stored in their internal
  773.     (possibly compiled, non-text) representation.
  774. */
  775. /* Resource type for scripts */
  776.  
  777. enum {
  778.     kOSAScriptResourceType        = kOSAGenericScriptingComponentSubtype
  779. };
  780.  
  781. /*
  782.         Default type given to OSAStore which creates "generic" loadable script
  783.           data descriptors.
  784. */
  785.  
  786. enum {
  787.     typeOSAGenericStorage        = kOSAScriptResourceType
  788. };
  789.  
  790. extern pascal OSAError OSALoad(ComponentInstance scriptingComponent, const AEDesc *scriptData, long modeFlags, OSAID *resultingScriptID)
  791.  FIVEWORDINLINE(0x2F3C, 0x000C, 0x0001, 0x7000, 0xA82A);
  792.  
  793. /*
  794.         OSAComponentFunctionInline(kOSASelectLoad, 12);
  795.     
  796.         Errors:
  797.             badComponentInstance        invalid scripting component instance
  798.             errOSASystemError
  799.             errOSABadStorageType:        scriptData not for this scripting component
  800.             errOSACorruptData:            data seems to be corrupt
  801.             errOSADataFormatObsolete    script data format is no longer supported
  802.             errOSADataFormatTooNew        script data format is from a newer version
  803.         
  804.         ModeFlags:
  805.             kOSAModePreventGetSource
  806. */
  807. extern pascal OSAError OSAStore(ComponentInstance scriptingComponent, OSAID scriptID, DescType desiredType, long modeFlags, AEDesc *resultingScriptData)
  808.  FIVEWORDINLINE(0x2F3C, 0x0010, 0x0002, 0x7000, 0xA82A);
  809.  
  810. /*
  811.         OSAComponentFunctionInline(kOSASelectStore, 16);
  812.     
  813.         Errors:
  814.             badComponentInstance    invalid scripting component instance
  815.             errOSASystemError
  816.             errOSAInvalidID
  817.             errOSABadStorageType:    desiredType not for this scripting component
  818.         
  819.         ModeFlags:
  820.             kOSAModePreventGetSource
  821.             kOSAModeDontStoreParent
  822. */
  823. /* Executing Scripts: */
  824. extern pascal OSAError OSAExecute(ComponentInstance scriptingComponent, OSAID compiledScriptID, OSAID contextID, long modeFlags, OSAID *resultingScriptValueID)
  825.  FIVEWORDINLINE(0x2F3C, 0x0010, 0x0003, 0x7000, 0xA82A);
  826.  
  827. /*
  828.         OSAComponentFunctionInline(kOSASelectExecute, 16);
  829.         This call runs a script.  The contextID represents the environment
  830.         with which global variables in the script are resolved.  The constant
  831.         kOSANullScript may be used for the contextID if the application wishes
  832.         to not deal with context directly (a default one is associated with each
  833.         scripting component instance).  The resultingScriptValueID is the 
  834.         result of evaluation, and contains a value which may be displayed using
  835.         the OSAGetSource call.  The modeFlags convey scripting component
  836.         specific information.
  837.     
  838.         Errors:
  839.             badComponentInstance    invalid scripting component instance
  840.             errOSASystemError
  841.             errOSAInvalidID
  842.             errOSAScriptError:        the executing script got an error
  843.     
  844.         ModeFlags:
  845.             kOSAModeNeverInteract
  846.             kOSAModeCanInteract
  847.             kOSAModeAlwaysInteract
  848.             kOSAModeCantSwitchLayer
  849.             kOSAModeDontReconnect
  850.             kOSAModeDoRecord
  851. */
  852. /* Displaying results: */
  853. extern pascal OSAError OSADisplay(ComponentInstance scriptingComponent, OSAID scriptValueID, DescType desiredType, long modeFlags, AEDesc *resultingText)
  854.  FIVEWORDINLINE(0x2F3C, 0x0010, 0x0004, 0x7000, 0xA82A);
  855.  
  856. /*
  857.         OSAComponentFunctionInline(kOSASelectDisplay, 16);
  858.         This call is used to convert results (script value IDs) into displayable
  859.         text. The desiredType should be at least typeChar, and modeFlags are
  860.         scripting system specific flags to control the formatting of the
  861.         resulting text. This call differs from OSAGetSource in that (1) it
  862.         always produces at least typeChar, (2) is only works on script values,
  863.         (3) it may display it's output in non-compilable form (e.g. without
  864.         string quotes, elipses inserted in long and/or circular lists, etc.) and
  865.         (4) it is required by the basic scripting interface.
  866.     
  867.         Errors:
  868.             badComponentInstance    invalid scripting component instance
  869.             errOSASystemError
  870.             errOSAInvalidID
  871.             errAECoercionFail:        desiredType not supported by scripting component
  872.     
  873.         ModeFlags:
  874.             kOSAModeDisplayForHumans
  875. */
  876. /* Getting Error Information: */
  877. extern pascal OSAError OSAScriptError(ComponentInstance scriptingComponent, OSType selector, DescType desiredType, AEDesc *resultingErrorDescription)
  878.  FIVEWORDINLINE(0x2F3C, 0x000C, 0x0005, 0x7000, 0xA82A);
  879.  
  880. /*
  881.         OSAComponentFunctionInline(kOSASelectScriptError, 12);
  882.         Whenever script execution returns errOSAExecutionError, this routine
  883.         may be used to get information about that error.  The selector describes
  884.         the type of information desired about the error (various selectors are
  885.         listed below).  The desiredType indicates the data type of the result
  886.         desired for that selector.
  887.     
  888.         Errors:
  889.             badComponentInstance    invalid scripting component instance
  890.             errOSASystemError
  891.             errOSABadSelector:        selector not supported by scripting component
  892.             errAECoercionFail:        desiredType not supported by scripting component
  893. */
  894. /* OSAScriptError selectors: */
  895. /*
  896.         This selector is used to determine the error number of a script error.
  897.         These error numbers may be either system error numbers, or error numbers
  898.         that are scripting component specific.
  899.         Required desiredTypes:    
  900.               typeShortInteger
  901. */
  902.  
  903. enum {
  904.     kOSAErrorNumber                = keyErrorNumber
  905. };
  906.  
  907. /*
  908.         This selector is used to determine the full error message associated
  909.         with the error number.  It should include the name of the application
  910.         which caused the error, as well as the specific error that occurred.
  911.         This selector is sufficient for simple error reporting (but see
  912.         kOSAErrorBriefMessage, below).
  913.         Required desiredTypes:
  914.             typeChar                    error message string
  915. */
  916.  
  917. enum {
  918.     kOSAErrorMessage            = keyErrorString
  919. };
  920.  
  921. /*
  922.         This selector is used to determine a brief error message associated with
  923.         the error number.  This message and should not mention the name of the
  924.         application which caused the error, any partial results or offending
  925.         object (see kOSAErrorApp, kOSAErrorPartialResult and
  926.         kOSAErrorOffendingObject, below).
  927.         Required desiredTypes:
  928.               typeChar                    brief error message string
  929. */
  930. /*  0x65727262  */
  931.  
  932. enum {
  933.     kOSAErrorBriefMessage        = 'errb'
  934. };
  935.  
  936. /*
  937.         This selector is used to determine which application actually got the
  938.         error (if it was the result of an AESend), or the current application
  939.         if ....
  940.         Required desiredTypes:
  941.               typeProcessSerialNumber        PSN of the errant application
  942.               typeChar                    name of the errant application
  943. */
  944. /*  0x65726170  */
  945.  
  946. enum {
  947.     kOSAErrorApp                = 'erap'
  948. };
  949.  
  950. /*
  951.         This selector is used to determine any partial result returned by an 
  952.         operation. If an AESend call failed, but a partial result was returned,
  953.         then the partial result may be returned as an AEDesc.
  954.         Required desiredTypes:
  955.               typeBest                    AEDesc of any partial result
  956. */
  957. /*  0x70746c72   */
  958.  
  959. enum {
  960.     kOSAErrorPartialResult        = 'ptlr'
  961. };
  962.  
  963. /*
  964.         This selector is used to determine any object which caused the error
  965.         that may have been indicated by an application.  The result is an 
  966.         AEDesc.
  967.         Required desiredTypes:
  968.               typeBest                    AEDesc of any offending object
  969. */
  970. /*  0x65726f62   */
  971.  
  972. enum {
  973.     kOSAErrorOffendingObject    = 'erob'
  974. };
  975.  
  976. /*
  977.         This selector is used to determine the type expected by a coercion 
  978.         operation if a type error occurred.
  979. */
  980. /*  0x65727274   */
  981.  
  982. enum {
  983.     kOSAErrorExpectedType        = 'errt'
  984. };
  985.  
  986. /*
  987.         This selector is used to determine the source text range (start and 
  988.         end positions) of where the error occurred.
  989.         Required desiredTypes:
  990.               typeOSAErrorRange
  991. */
  992. /*  0x65726e67  */
  993.  
  994. enum {
  995.     kOSAErrorRange                = 'erng'
  996. };
  997.  
  998. /*
  999.         An AERecord type containing keyOSASourceStart and keyOSASourceEnd fields
  1000.         of type short.
  1001. */
  1002. /*  0x65726e67   */
  1003.  
  1004. enum {
  1005.     typeOSAErrorRange            = 'erng'
  1006. };
  1007.  
  1008. /* Field of a typeOSAErrorRange record of typeShortInteger */
  1009. /*  0x73726373    */
  1010.  
  1011. enum {
  1012.     keyOSASourceStart            = 'srcs'
  1013. };
  1014.  
  1015. /* Field of a typeOSAErrorRange record of typeShortInteger */
  1016. /*  0x73726365   */
  1017.  
  1018. enum {
  1019.     keyOSASourceEnd                = 'srce'
  1020. };
  1021.  
  1022. /* Disposing Script IDs: */
  1023. extern pascal OSAError OSADispose(ComponentInstance scriptingComponent, OSAID scriptID)
  1024.  FIVEWORDINLINE(0x2F3C, 0x0004, 0x0006, 0x7000, 0xA82A);
  1025.  
  1026. /*
  1027.         OSAComponentFunctionInline(kOSASelectDispose, 4);
  1028.         Disposes a script or context.
  1029.     
  1030.         Errors:
  1031.             badComponentInstance    invalid scripting component instance
  1032.             errOSASystemError
  1033.             errOSAInvalidID
  1034. */
  1035. /* Getting and Setting Script Information: */
  1036. extern pascal OSAError OSASetScriptInfo(ComponentInstance scriptingComponent, OSAID scriptID, OSType selector, long value)
  1037.  FIVEWORDINLINE(0x2F3C, 0x000C, 0x0007, 0x7000, 0xA82A);
  1038.  
  1039. /*
  1040.         OSAComponentFunctionInline(kOSASelectSetScriptInfo, 12);
  1041.     
  1042.         Errors:
  1043.             badComponentInstance    invalid scripting component instance
  1044.             errOSASystemError
  1045.             errOSAInvalidID
  1046.             errOSABadSelector:        selector not supported by scripting component
  1047.                                     or selector not for this scriptID
  1048. */
  1049. extern pascal OSAError OSAGetScriptInfo(ComponentInstance scriptingComponent, OSAID scriptID, OSType selector, long *result)
  1050.  FIVEWORDINLINE(0x2F3C, 0x000C, 0x0008, 0x7000, 0xA82A);
  1051.  
  1052. /*
  1053.         OSAComponentFunctionInline(kOSASelectGetScriptInfo, 12);
  1054.     
  1055.         Errors:
  1056.             badComponentInstance    invalid scripting component instance
  1057.             errOSASystemError
  1058.             errOSAInvalidID
  1059.             errOSABadSelector:        selector not supported by scripting component
  1060.                                     or selector not for this scriptID
  1061. */
  1062. /*
  1063.  Manipulating the ActiveProc:
  1064.  
  1065.     Scripting systems will supply default values for these procedures if they
  1066.     are not set by the client:
  1067. */
  1068. typedef pascal OSErr (*OSAActiveProcPtr)(long refCon);
  1069.  
  1070. #if GENERATINGCFM
  1071. typedef UniversalProcPtr OSAActiveUPP;
  1072. #else
  1073. typedef OSAActiveProcPtr OSAActiveUPP;
  1074. #endif
  1075.  
  1076. enum {
  1077.     uppOSAActiveProcInfo = kPascalStackBased
  1078.          | RESULT_SIZE(SIZE_CODE(sizeof(OSErr)))
  1079.          | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(long)))
  1080. };
  1081.  
  1082. #if GENERATINGCFM
  1083. #define NewOSAActiveProc(userRoutine)        \
  1084.         (OSAActiveUPP) NewRoutineDescriptor((ProcPtr)(userRoutine), uppOSAActiveProcInfo, GetCurrentArchitecture())
  1085. #else
  1086. #define NewOSAActiveProc(userRoutine)        \
  1087.         ((OSAActiveUPP) (userRoutine))
  1088. #endif
  1089.  
  1090. #if GENERATINGCFM
  1091. #define CallOSAActiveProc(userRoutine, refCon)        \
  1092.         CallUniversalProc((UniversalProcPtr)(userRoutine), uppOSAActiveProcInfo, (refCon))
  1093. #else
  1094. #define CallOSAActiveProc(userRoutine, refCon)        \
  1095.         (*(userRoutine))((refCon))
  1096. #endif
  1097. extern pascal OSAError OSASetActiveProc(ComponentInstance scriptingComponent, OSAActiveUPP activeProc, long refCon)
  1098.  FIVEWORDINLINE(0x2F3C, 0x0008, 0x0009, 0x7000, 0xA82A);
  1099.  
  1100. /*
  1101.         OSAComponentFunctionInline(kOSASelectSetActiveProc, 8);
  1102.         If activeProc is nil, the default activeProc is used.
  1103.     
  1104.         Errors:
  1105.             badComponentInstance    invalid scripting component instance
  1106.             errOSASystemError
  1107. */
  1108. extern pascal OSAError OSAGetActiveProc(ComponentInstance scriptingComponent, OSAActiveUPP *activeProc, long *refCon)
  1109.  FIVEWORDINLINE(0x2F3C, 0x0008, 0x000A, 0x7000, 0xA82A);
  1110.  
  1111. /*
  1112.         OSAComponentFunctionInline(kOSASelectGetActiveProc, 8);
  1113.     
  1114.         Errors:
  1115.             badComponentInstance    invalid scripting component instance
  1116.             errOSASystemError
  1117. */
  1118. /*
  1119. *************************************************************************
  1120.     OSA Optional Compiling Interface
  1121. **************************************************************************
  1122.     Scripting components that support the Compiling interface have the 
  1123.     kOSASupportsCompiling bit set in it's ComponentDescription.
  1124. *************************************************************************
  1125. */
  1126. extern pascal OSAError OSAScriptingComponentName(ComponentInstance scriptingComponent, AEDesc *resultingScriptingComponentName)
  1127.  FIVEWORDINLINE(0x2F3C, 0x0004, 0x0102, 0x7000, 0xA82A);
  1128.  
  1129. /*
  1130.         OSAComponentFunctionInline(kOSASelectScriptingComponentName, 4);
  1131.         Given a scripting component, this routine returns the name of that
  1132.         scripting component in a type that is coercable to text (typeChar).
  1133.         The generic scripting component returns the name of the default
  1134.         scripting component.  This name should be sufficient to convey to the
  1135.         user the kind of script (syntax) he is expected to write.
  1136.     
  1137.         Errors:
  1138.             badComponentInstance    invalid scripting component instance
  1139.             errOSASystemError
  1140. */
  1141. extern pascal OSAError OSACompile(ComponentInstance scriptingComponent, const AEDesc *sourceData, long modeFlags, OSAID *previousAndResultingScriptID)
  1142.  FIVEWORDINLINE(0x2F3C, 0x000C, 0x0103, 0x7000, 0xA82A);
  1143.  
  1144. /*
  1145.         OSAComponentFunctionInline(kOSASelectCompile, 12);
  1146.         Coerces input desc (possibly text) into a script's internal format.
  1147.         Once compiled, the script is ready to run.  The modeFlags convey
  1148.         scripting component specific information.  The previous script ID
  1149.         (result parameter) is made to refer to the newly compiled script,
  1150.         unless it was originally kOSANullScript.  In this case a new script
  1151.         ID is created and used.
  1152.     
  1153.         Errors:
  1154.             badComponentInstance    invalid scripting component instance
  1155.             errOSASystemError
  1156.             errAECoercionFail:        sourceData is not compilable
  1157.             errOSAScriptError:        sourceData was a bad script (syntax error)
  1158.             errOSAInvalidID:        previousAndResultingCompiledScriptID was not
  1159.                                     valid on input
  1160.     
  1161.         ModeFlags:
  1162.             kOSAModePreventGetSource
  1163.             kOSAModeCompileIntoContext
  1164.             kOSAModeAugmentContext
  1165.             kOSAModeNeverInteract
  1166.             kOSAModeCanInteract
  1167.             kOSAModeAlwaysInteract
  1168.             kOSAModeCantSwitchLayer
  1169.             kOSAModeDontReconnect
  1170.             kOSAModeDoRecord
  1171. */
  1172. extern pascal OSAError OSACopyID(ComponentInstance scriptingComponent, OSAID fromID, OSAID *toID)
  1173.  FIVEWORDINLINE(0x2F3C, 0x0008, 0x0104, 0x7000, 0xA82A);
  1174.  
  1175. /*
  1176.         OSAComponentFunctionInline(kOSASelectCopyID, 8);
  1177.         If toID is a reference to kOSANullScript then it is updated to have a
  1178.         new scriptID value.  This call can be used to perform undo or revert
  1179.         operations on scripts. 
  1180.     
  1181.         Errors:
  1182.             badComponentInstance    invalid scripting component instance
  1183.             errOSASystemError
  1184.             errOSAInvalidID
  1185. */
  1186. /*
  1187. *************************************************************************
  1188.     OSA Optional GetSource Interface
  1189. **************************************************************************
  1190.     Scripting components that support the GetSource interface have the 
  1191.     kOSASupportsGetSource bit set in it's ComponentDescription.
  1192. *************************************************************************
  1193. */
  1194. extern pascal OSAError OSAGetSource(ComponentInstance scriptingComponent, OSAID scriptID, DescType desiredType, AEDesc *resultingSourceData)
  1195.  FIVEWORDINLINE(0x2F3C, 0x000C, 0x0201, 0x7000, 0xA82A);
  1196.  
  1197. /*
  1198.         OSAComponentFunctionInline(kOSASelectGetSource, 12);
  1199.         This routine causes a compiled script to be output in a form (possibly
  1200.         text) such that it is suitable to be passed back to OSACompile.
  1201.  
  1202.         Errors:
  1203.             badComponentInstance    invalid scripting component instance
  1204.             errOSASystemError
  1205.             errOSAInvalidID
  1206.             errOSASourceNotAvailable    can't get source for this scriptID
  1207. */
  1208. /*
  1209. *************************************************************************
  1210.     OSA Optional AECoercion Interface
  1211. **************************************************************************
  1212.     Scripting components that support the AECoercion interface have the 
  1213.     kOSASupportsAECoercion bit set in it's ComponentDescription.
  1214. *************************************************************************
  1215. */
  1216. extern pascal OSAError OSACoerceFromDesc(ComponentInstance scriptingComponent, const AEDesc *scriptData, long modeFlags, OSAID *resultingScriptID)
  1217.  FIVEWORDINLINE(0x2F3C, 0x000C, 0x0301, 0x7000, 0xA82A);
  1218.  
  1219. /*
  1220.         OSAComponentFunctionInline(kOSASelectCoerceFromDesc, 12);
  1221.         This routine causes script data to be coerced into a script value.
  1222.         If the scriptData is an AppleEvent, then the resultingScriptID is a
  1223.         compiled script ID (mode flags for OSACompile may be used in this case).
  1224.         Other scriptData descriptors create script value IDs.
  1225.     
  1226.         Errors:
  1227.             badComponentInstance    invalid scripting component instance
  1228.             errOSASystemError
  1229.     
  1230.         ModeFlags:
  1231.             kOSAModePreventGetSource
  1232.             kOSAModeCompileIntoContext
  1233.             kOSAModeNeverInteract
  1234.             kOSAModeCanInteract
  1235.             kOSAModeAlwaysInteract
  1236.             kOSAModeCantSwitchLayer
  1237.             kOSAModeDontReconnect
  1238.             kOSAModeDoRecord
  1239. */
  1240. extern pascal OSAError OSACoerceToDesc(ComponentInstance scriptingComponent, OSAID scriptID, DescType desiredType, long modeFlags, AEDesc *result)
  1241.  FIVEWORDINLINE(0x2F3C, 0x0010, 0x0302, 0x7000, 0xA82A);
  1242.  
  1243. /*
  1244.         OSAComponentFunctionInline(kOSASelectCoerceToDesc, 16);
  1245.         This routine causes a script value to be coerced into any desired form.
  1246.         If the scriptID denotes a compiled script, then it may be coerced to 
  1247.         typeAppleEvent.
  1248.     
  1249.         Errors:
  1250.             badComponentInstance    invalid scripting component instance
  1251.             errOSASystemError
  1252.             errOSAInvalidID
  1253. */
  1254. /*
  1255. *************************************************************************
  1256.     OSA Optional AESending Interface
  1257. **************************************************************************
  1258.     Scripting components that support the AESending interface have the 
  1259.     kOSASupportsAESending bit set in it's ComponentDescription.
  1260. *************************************************************************
  1261. */
  1262. /*
  1263.     Scripting systems will supply default values for these procedures if they
  1264.     are not set by the client:
  1265. */
  1266. extern pascal OSAError OSASetSendProc(ComponentInstance scriptingComponent, OSASendUPP sendProc, long refCon)
  1267.  FIVEWORDINLINE(0x2F3C, 0x0008, 0x0401, 0x7000, 0xA82A);
  1268.  
  1269. /*
  1270.         OSAComponentFunctionInline(kOSASelectSetSendProc, 8);
  1271.         If sendProc is nil, the default sendProc is used.
  1272.     
  1273.         Errors:
  1274.             badComponentInstance    invalid scripting component instance
  1275.             errOSASystemError
  1276. */
  1277. extern pascal OSAError OSAGetSendProc(ComponentInstance scriptingComponent, OSASendUPP *sendProc, long *refCon)
  1278.  FIVEWORDINLINE(0x2F3C, 0x0008, 0x0402, 0x7000, 0xA82A);
  1279.  
  1280. /*
  1281.         OSAComponentFunctionInline(kOSASelectGetSendProc, 8);
  1282.     
  1283.         Errors:
  1284.             badComponentInstance    invalid scripting component instance
  1285.             errOSASystemError
  1286. */
  1287. extern pascal OSAError OSASetCreateProc(ComponentInstance scriptingComponent, OSACreateAppleEventUPP createProc, long refCon)
  1288.  FIVEWORDINLINE(0x2F3C, 0x0008, 0x0403, 0x7000, 0xA82A);
  1289.  
  1290. /*
  1291.         OSAComponentFunctionInline(kOSASelectSetCreateProc, 8);
  1292.         If createProc is nil, the default createProc is used.
  1293.     
  1294.         Errors:
  1295.             badComponentInstance    invalid scripting component instance
  1296.             errOSASystemError
  1297. */
  1298. extern pascal OSAError OSAGetCreateProc(ComponentInstance scriptingComponent, OSACreateAppleEventUPP *createProc, long *refCon)
  1299.  FIVEWORDINLINE(0x2F3C, 0x0008, 0x0404, 0x7000, 0xA82A);
  1300.  
  1301. /*
  1302.         OSAComponentFunctionInline(kOSASelectGetCreateProc, 8);
  1303.     
  1304.         Errors:
  1305.             badComponentInstance    invalid scripting component instance
  1306.             errOSASystemError
  1307. */
  1308. extern pascal OSAError OSASetDefaultTarget(ComponentInstance scriptingComponent, const AEAddressDesc *target)
  1309.  FIVEWORDINLINE(0x2F3C, 0x0004, 0x0405, 0x7000, 0xA82A);
  1310.  
  1311. /*
  1312.         OSAComponentFunctionInline(kOSASelectSetDefaultTarget, 4);
  1313.         This routine sets the default target application for AE sending.
  1314.         It also establishes the default target from which terminologies come.
  1315.         It is effectively like having an AppleScript "tell" statement around
  1316.         the entire program.  If this routine is not called, or if the target 
  1317.         is a null AEDesc, then the current application is the default target.
  1318.     
  1319.         Errors:
  1320.             badComponentInstance    invalid scripting component instance
  1321.             errOSASystemError
  1322. */
  1323. /*
  1324. *************************************************************************
  1325.     OSA Optional Recording Interface
  1326. **************************************************************************
  1327.     Scripting components that support the Recording interface have the 
  1328.     kOSASupportsRecording bit set in it's ComponentDescription.
  1329. *************************************************************************
  1330. */
  1331. extern pascal OSAError OSAStartRecording(ComponentInstance scriptingComponent, OSAID *compiledScriptToModifyID)
  1332.  FIVEWORDINLINE(0x2F3C, 0x0004, 0x0501, 0x7000, 0xA82A);
  1333.  
  1334. /*
  1335.         OSAComponentFunctionInline(kOSASelectStartRecording, 4);
  1336.         Starts recording.  If compiledScriptToModifyID is kOSANullScript, a
  1337.         new script ID is created and returned.  If the current application has
  1338.         a handler for the kOSARecordedText event, then kOSARecordedText events
  1339.         are sent to the application containing the text of each AppleEvent 
  1340.         recorded.
  1341.     
  1342.         Errors:
  1343.             badComponentInstance    invalid scripting component instance
  1344.             errOSASystemError
  1345.             errOSAInvalidID
  1346.             errOSARecordingIsAlreadyOn
  1347. */
  1348. extern pascal OSAError OSAStopRecording(ComponentInstance scriptingComponent, OSAID compiledScriptID)
  1349.  FIVEWORDINLINE(0x2F3C, 0x0004, 0x0502, 0x7000, 0xA82A);
  1350.  
  1351. /*
  1352.         OSAComponentFunctionInline(kOSASelectStopRecording, 4);
  1353.         If compiledScriptID is not being recorded into or recording is not
  1354.         currently on, no error is returned.
  1355.     
  1356.         Errors:
  1357.             badComponentInstance    invalid scripting component instance
  1358.             errOSASystemError
  1359.             errOSAInvalidID
  1360. */
  1361. /*
  1362. *************************************************************************
  1363.     OSA Optional Convenience Interface
  1364. **************************************************************************
  1365.     Scripting components that support the Convenience interface have the 
  1366.     kOSASupportsConvenience bit set in it's ComponentDescription.
  1367. *************************************************************************
  1368. */
  1369. extern pascal OSAError OSALoadExecute(ComponentInstance scriptingComponent, const AEDesc *scriptData, OSAID contextID, long modeFlags, OSAID *resultingScriptValueID)
  1370.  FIVEWORDINLINE(0x2F3C, 0x0010, 0x0601, 0x7000, 0xA82A);
  1371.  
  1372. /*
  1373.         OSAComponentFunctionInline(kOSASelectLoadExecute, 16);
  1374.         This routine is effectively equivalent to calling OSALoad followed by
  1375.         OSAExecute.  After execution, the compiled source is disposed.  Only the
  1376.         resulting value ID is retained.
  1377.     
  1378.         Errors:
  1379.             badComponentInstance        invalid scripting component instance
  1380.             errOSASystemError
  1381.             errOSABadStorageType:        scriptData not for this scripting component
  1382.             errOSACorruptData:            data seems to be corrupt
  1383.             errOSADataFormatObsolete    script data format is no longer supported
  1384.             errOSADataFormatTooNew        script data format is from a newer version
  1385.             errOSAInvalidID
  1386.             errOSAScriptError:            the executing script got an error
  1387.     
  1388.         ModeFlags:
  1389.             kOSAModeNeverInteract
  1390.             kOSAModeCanInteract
  1391.             kOSAModeAlwaysInteract
  1392.             kOSAModeCantSwitchLayer
  1393.             kOSAModeDontReconnect
  1394.             kOSAModeDoRecord
  1395. */
  1396. extern pascal OSAError OSACompileExecute(ComponentInstance scriptingComponent, const AEDesc *sourceData, OSAID contextID, long modeFlags, OSAID *resultingScriptValueID)
  1397.  FIVEWORDINLINE(0x2F3C, 0x0010, 0x0602, 0x7000, 0xA82A);
  1398.  
  1399. /*
  1400.         OSAComponentFunctionInline(kOSASelectCompileExecute, 16);
  1401.         This routine is effectively equivalent to calling OSACompile followed by
  1402.         OSAExecute.  After execution, the compiled source is disposed.  Only the
  1403.         resulting value ID is retained.
  1404.     
  1405.         Errors:
  1406.             badComponentInstance    invalid scripting component instance
  1407.             errOSASystemError
  1408.             errAECoercionFail:        sourceData is not compilable
  1409.             errOSAScriptError:        sourceData was a bad script (syntax error)
  1410.             errOSAInvalidID:        previousAndResultingCompiledScriptID was not
  1411.                                     valid on input
  1412.             errOSAScriptError:        the executing script got an error
  1413.     
  1414.         ModeFlags:
  1415.             kOSAModeNeverInteract
  1416.             kOSAModeCanInteract
  1417.             kOSAModeAlwaysInteract
  1418.             kOSAModeCantSwitchLayer
  1419.             kOSAModeDontReconnect
  1420.             kOSAModeDoRecord
  1421. */
  1422. extern pascal OSAError OSADoScript(ComponentInstance scriptingComponent, const AEDesc *sourceData, OSAID contextID, DescType desiredType, long modeFlags, AEDesc *resultingText)
  1423.  FIVEWORDINLINE(0x2F3C, 0x0014, 0x0603, 0x7000, 0xA82A);
  1424.  
  1425. /*
  1426.         OSAComponentFunctionInline(kOSASelectDoScript, 20);
  1427.         This routine is effectively equivalent to calling OSACompile followed by
  1428.         OSAExecute and then OSADisplay.  After execution, the compiled source
  1429.         and the resulting value are is disposed.  Only the resultingText
  1430.         descriptor is retained.  If a script error occur during processing, the 
  1431.         resultingText gets the error message of the error, and errOSAScriptError
  1432.         is returned.  OSAScriptError may still be used to extract more 
  1433.         information about the particular error.
  1434.     
  1435.         Errors:
  1436.             badComponentInstance    invalid scripting component instance
  1437.             errOSASystemError
  1438.             errAECoercionFail:        sourceData is not compilable or 
  1439.                                     desiredType not supported by scripting component
  1440.             errOSAScriptError:        sourceData was a bad script (syntax error)
  1441.             errOSAInvalidID:        previousAndResultingCompiledScriptID was not
  1442.                                     valid on input
  1443.             errOSAScriptError:        the executing script got an error
  1444.     
  1445.         ModeFlags:
  1446.             kOSAModeNeverInteract
  1447.             kOSAModeCanInteract
  1448.             kOSAModeAlwaysInteract
  1449.             kOSAModeCantSwitchLayer
  1450.             kOSAModeDontReconnect
  1451.             kOSAModeDoRecord
  1452.             kOSAModeDisplayForHumans
  1453. */
  1454. /*
  1455. *************************************************************************
  1456.     OSA Optional Dialects Interface
  1457. **************************************************************************
  1458.     Scripting components that support the Dialects interface have the 
  1459.     kOSASupportsDialects bit set in it's ComponentDescription.
  1460. *************************************************************************
  1461. */
  1462. /*
  1463.     These calls allows an scripting component that supports different dialects
  1464.     to dynamically switch between those dialects.  Although this interface is
  1465.     specified, the particular dialect codes are scripting component dependent.
  1466. */
  1467. extern pascal OSAError OSASetCurrentDialect(ComponentInstance scriptingComponent, short dialectCode)
  1468.  FIVEWORDINLINE(0x2F3C, 0x0002, 0x0701, 0x7000, 0xA82A);
  1469.  
  1470. /*
  1471.         OSAComponentFunctionInline(kOSASelectSetCurrentDialect, 2);
  1472.     
  1473.         Errors:
  1474.             badComponentInstance    invalid scripting component instance
  1475.             errOSASystemError
  1476.             errOSANoSuchDialect:    invalid dialectCode
  1477. */
  1478. extern pascal OSAError OSAGetCurrentDialect(ComponentInstance scriptingComponent, short *resultingDialectCode)
  1479.  FIVEWORDINLINE(0x2F3C, 0x0004, 0x0702, 0x7000, 0xA82A);
  1480.  
  1481. /*
  1482.         OSAComponentFunctionInline(kOSASelectGetCurrentDialect, 4);
  1483.     
  1484.         Errors:
  1485.             badComponentInstance    invalid scripting component instance
  1486.             errOSASystemError
  1487. */
  1488. extern pascal OSAError OSAAvailableDialects(ComponentInstance scriptingComponent, AEDesc *resultingDialectInfoList)
  1489.  FIVEWORDINLINE(0x2F3C, 0x0004, 0x0703, 0x7000, 0xA82A);
  1490.  
  1491. /*
  1492.         OSAComponentFunctionInline(kOSASelectAvailableDialects, 4);
  1493.         This call return an AEList containing information about each of the
  1494.         currently available dialects of a scripting component.  Each item
  1495.         is an AERecord of typeOSADialectInfo that contains at least the fields
  1496.         keyOSADialectName, keyOSADialectCode, KeyOSADialectLangCode and 
  1497.         keyOSADialectScriptCode.
  1498.     
  1499.         Errors:
  1500.             badComponentInstance    invalid scripting component instance
  1501.             errOSASystemError
  1502. */
  1503. extern pascal OSAError OSAGetDialectInfo(ComponentInstance scriptingComponent, short dialectCode, OSType selector, AEDesc *resultingDialectInfo)
  1504.  FIVEWORDINLINE(0x2F3C, 0x000A, 0x0704, 0x7000, 0xA82A);
  1505.  
  1506. /*
  1507.         OSAComponentFunctionInline(kOSASelectGetDialectInfo, 10);
  1508.         This call gives information about the specified dialect of a scripting
  1509.         component. It returns an AEDesc whose type depends on the selector 
  1510.         specified. Available selectors are the same as the field keys for a
  1511.         dialect info record. The type of AEDesc returned is the same as the 
  1512.         type of the field that has same key as the selector.
  1513.     
  1514.         Errors:
  1515.             badComponentInstance    invalid scripting component instance
  1516.             errOSASystemError
  1517.              errOSABadSelector
  1518.             errOSANoSuchDialect:    invalid dialectCode
  1519. */
  1520. extern pascal OSAError OSAAvailableDialectCodeList(ComponentInstance scriptingComponent, AEDesc *resultingDialectCodeList)
  1521.  FIVEWORDINLINE(0x2F3C, 0x0004, 0x0705, 0x7000, 0xA82A);
  1522.  
  1523. /*
  1524.         OSAComponentFunctionInline(kOSASelectAvailableDialectCodeList, 4);
  1525.         This is alternative to OSAGetAvailableDialectCodeList. Use this call
  1526.         and  OSAGetDialectInfo to get information on dialects.
  1527.         This call return an AEList containing dialect code for each of the
  1528.         currently available dialects of a scripting component. Each dialect
  1529.         code is a short integer of type typeShortInteger.
  1530.     
  1531.         Errors:
  1532.             badComponentInstance    invalid scripting component instance
  1533.             errOSASystemError
  1534.  
  1535.         Type of a dialect info record containing at least keyOSADialectName
  1536.         and keyOSADialectCode fields.
  1537.  
  1538.         keys for dialect info record, also used as selectors to OSAGetDialectInfo.
  1539.  
  1540.         Field of a typeOSADialectInfo record of typeChar.
  1541.         Field of a typeOSADialectInfo record of typeShortInteger.
  1542.         Field of a typeOSADialectInfo record of typeShortInteger.
  1543.         Field of a typeOSADialectInfo record of typeShortInteger.
  1544. */
  1545. /*
  1546. *************************************************************************
  1547.     OSA Optional Event Handling Interface
  1548. **************************************************************************
  1549.     Scripting components that support the Event Handling interface have the 
  1550.     kOSASupportsEventHandling bit set in it's ComponentDescription.
  1551. *************************************************************************
  1552. */
  1553. extern pascal OSAError OSASetResumeDispatchProc(ComponentInstance scriptingComponent, AEEventHandlerUPP resumeDispatchProc, long refCon)
  1554.  FIVEWORDINLINE(0x2F3C, 0x0008, 0x0801, 0x7000, 0xA82A);
  1555.  
  1556. /*
  1557.         OSAComponentFunctionInline(kOSASelectSetResumeDispatchProc, 8);
  1558.         This function is used to set the ResumeDispatchProc that will be used
  1559.         by OSAExecuteEvent and OSADoEvent if either no event handler can be
  1560.         found in the context, or the context event hander "continues" control
  1561.         onward. The two constants kOSAUseStandardDispatch and kOSANoDispatch
  1562.         may also be passed to this routine indicating that the handler registered
  1563.         in the application with AEInstallEventHandler should be used, or no
  1564.         dispatch should occur, respectively.
  1565.     
  1566.         Errors:
  1567.             badComponentInstance    invalid scripting component instance
  1568.             errOSASystemError
  1569. */
  1570.  
  1571. enum {
  1572.     kOSAUseStandardDispatch        = kAEUseStandardDispatch
  1573. };
  1574.  
  1575. /*
  1576.         Special ResumeDispatchProc constant which may be passed to 
  1577.         OSASetResumeDispatchProc indicating that the handler registered
  1578.         in the application with AEInstallEventHandler should be used.
  1579.         
  1580.         NOTE:    Had to remove the cast (AEEventHandlerUPP).  The C compiler
  1581.                 doesn't allow pointer types to be assigned to an enum.  All
  1582.                 constants must be assigned as enums to translate properly to
  1583.                 Pascal.
  1584. */
  1585.  
  1586. enum {
  1587.     kOSANoDispatch                = kAENoDispatch
  1588. };
  1589.  
  1590. /*
  1591.         Special ResumeDispatchProc constant which may be passed to 
  1592.         OSASetResumeDispatchProc indicating that no dispatch should occur.
  1593.         
  1594.         NOTE:    Had to remove the cast (AEEventHandlerUPP).  The C compiler
  1595.                 doesn't allow pointer types to be assigned to an enum.  All
  1596.                 constants must be assigned as enums to translate properly to
  1597.                 Pascal.
  1598. */
  1599.  
  1600. enum {
  1601.     kOSADontUsePhac                = 0x0001
  1602. };
  1603.  
  1604. /*
  1605.         Special refCon constant that may be given to OSASetResumeDispatchProc
  1606.         only when kOSAUseStandardDispatch is used as the ResumeDispatchProc.
  1607.         This causes the standard dispatch to be performed, except the phac
  1608.         handler is not called.  This is useful during tinkerability, when
  1609.         the phac handler is used to lookup a context associated with an event's 
  1610.         direct parameter, and call OSAExecuteEvent or OSADoEvent.  Failure to
  1611.         bypass the phac handler would result in an infinite loop.
  1612. */
  1613. extern pascal OSAError OSAGetResumeDispatchProc(ComponentInstance scriptingComponent, AEEventHandlerUPP *resumeDispatchProc, long *refCon)
  1614.  FIVEWORDINLINE(0x2F3C, 0x0008, 0x0802, 0x7000, 0xA82A);
  1615.  
  1616. /*
  1617.         OSAComponentFunctionInline(kOSASelectGetResumeDispatchProc, 8);
  1618.         Returns the registered ResumeDispatchProc.  If no ResumeDispatchProc has
  1619.         been registered, then kOSAUseStandardDispatch (the default) is returned.
  1620.     
  1621.         Errors:
  1622.             badComponentInstance    invalid scripting component instance
  1623.             errOSASystemError
  1624. */
  1625. extern pascal OSAError OSAExecuteEvent(ComponentInstance scriptingComponent, const AppleEvent *theAppleEvent, OSAID contextID, long modeFlags, OSAID *resultingScriptValueID)
  1626.  FIVEWORDINLINE(0x2F3C, 0x0010, 0x0803, 0x7000, 0xA82A);
  1627.  
  1628. /*
  1629.         OSAComponentFunctionInline(kOSASelectExecuteEvent, 16);
  1630.         This call is similar to OSAExecute except the initial command to
  1631.         execute comes in the form of an AppleEvent.  If the contextID
  1632.         defines any event handlers for that event, they are used to process
  1633.         the event.  If no event handler can be found in the context
  1634.         errAEEventNotHandled is returned.  If an event handler is found and
  1635.         the hander "continues" control onward, the ResumeDispatchProc
  1636.         (registered with OSASetResumeDispatchProc, above) is called given the
  1637.         AppleEvent.  The result is returned as a scriptValueID.
  1638.     
  1639.         Errors:
  1640.             badComponentInstance    invalid scripting component instance
  1641.             errOSASystemError
  1642.             errOSAInvalidID
  1643.             errOSAScriptError:        the executing script got an error
  1644.             errAEEventNotHandled:    no handler for event in contextID
  1645.     
  1646.         ModeFlags:
  1647.             kOSAModeNeverInteract
  1648.             kOSAModeCanInteract
  1649.             kOSAModeAlwaysInteract
  1650.             kOSAModeCantSwitchLayer
  1651.             kOSAModeDontReconnect
  1652.             kOSAModeDoRecord
  1653. */
  1654. extern pascal OSAError OSADoEvent(ComponentInstance scriptingComponent, const AppleEvent *theAppleEvent, OSAID contextID, long modeFlags, AppleEvent *reply)
  1655.  FIVEWORDINLINE(0x2F3C, 0x0010, 0x0804, 0x7000, 0xA82A);
  1656.  
  1657. /*
  1658.         OSAComponentFunctionInline(kOSASelectDoEvent, 16);
  1659.         This call is similar to OSADoScript except the initial command to
  1660.         execute comes in the form of an AppleEvent, and the result is an 
  1661.         AppleEvent reply record.  If the contextID defines any event handlers
  1662.         for that event, they are used to process the event.  If no event handler
  1663.         can be found in the context errAEEventNotHandled is returned.  If an
  1664.         event handler is found and the hander "continues" control onward, the
  1665.         ResumeDispatchProc (registered with OSASetResumeDispatchProc, above) is
  1666.         called given the AppleEvent.  The result is returned in the form of an
  1667.         AppleEvent reply descriptor. If at any time the script gets an error, or
  1668.         if the ResumeDispatchProc returns a reply event indicating an error,
  1669.         then the OSADoEvent call itself returns an error reply (i.e. OSADoEvent
  1670.         should never return errOSAScriptError).  Any error result returned by
  1671.         the ResumeDispatchProc will be returned by OSADoEvent.
  1672.     
  1673.         Errors:
  1674.             badComponentInstance    invalid scripting component instance
  1675.             errOSASystemError
  1676.             errOSAInvalidID
  1677.             errAEEventNotHandled:    no handler for event in contextID
  1678.     
  1679.         ModeFlags:
  1680.             kOSAModeNeverInteract
  1681.             kOSAModeCanInteract
  1682.             kOSAModeAlwaysInteract
  1683.             kOSAModeCantSwitchLayer
  1684.             kOSAModeDontReconnect
  1685.             kOSAModeDoRecord
  1686. */
  1687. extern pascal OSAError OSAMakeContext(ComponentInstance scriptingComponent, const AEDesc *contextName, OSAID parentContext, OSAID *resultingContextID)
  1688.  FIVEWORDINLINE(0x2F3C, 0x000C, 0x0805, 0x7000, 0xA82A);
  1689.  
  1690. /*
  1691.         OSAComponentFunctionInline(kOSASelectMakeContext, 12);
  1692.         Makes a new empty context which may be passed to OSAExecute or 
  1693.         OSAExecuteEvent.  If contextName is typeNull, an unnamed context is
  1694.         created. If parentContext is kOSANullScript then the resulting context
  1695.         does not inherit bindings from any other context.
  1696.     
  1697.         Errors:
  1698.             badComponentInstance    invalid scripting component instance
  1699.             errOSASystemError
  1700.             errOSAInvalidID
  1701.             errAECoercionFail:        contextName is invalid
  1702. */
  1703. #endif
  1704.  
  1705. #if PRAGMA_ALIGN_SUPPORTED
  1706. #pragma options align=reset
  1707. #endif
  1708.  
  1709. #if PRAGMA_IMPORT_SUPPORTED
  1710. #pragma import off
  1711. #endif
  1712.  
  1713. #ifdef __cplusplus
  1714. }
  1715. #endif
  1716.  
  1717. #endif /* __OSA__ */
  1718.  
  1719.